home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / g_man / cat3 / OpenGL / glstencilop.z / glstencilop
Encoding:
Text File  |  2002-10-03  |  8.5 KB  |  134 lines
  1.  
  2.  
  3.  
  4. ggggllllSSSStttteeeennnncccciiiillllOOOOpppp((((3333GGGG))))                OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee                ggggllllSSSStttteeeennnncccciiiillllOOOOpppp((((3333GGGG))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ggggllllSSSStttteeeennnncccciiiillllOOOOpppp - set stencil test actions
  10.  
  11.  
  12. CCCC SSSSPPPPEEEECCCCIIIIFFFFIIIICCCCAAAATTTTIIIIOOOONNNN
  13.      void ggggllllSSSStttteeeennnncccciiiillllOOOOpppp( GLenum _f_a_i_l,
  14.                        GLenum _z_f_a_i_l,
  15.                        GLenum _z_p_a_s_s )
  16.  
  17.  
  18. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS
  19.      _f_a_i_l   Specifies the action to take when the stencil test fails.  Six
  20.             symbolic constants are accepted:  GGGGLLLL____KKKKEEEEEEEEPPPP, GGGGLLLL____ZZZZEEEERRRROOOO, GGGGLLLL____RRRREEEEPPPPLLLLAAAACCCCEEEE,
  21.             GGGGLLLL____IIIINNNNCCCCRRRR, GGGGLLLL____DDDDEEEECCCCRRRR, and GGGGLLLL____IIIINNNNVVVVEEEERRRRTTTT. The initial value is GGGGLLLL____KKKKEEEEEEEEPPPP.
  22.  
  23.      _z_f_a_i_l  Specifies the stencil action when the stencil test passes, but the
  24.             depth test fails.  _z_f_a_i_l accepts the same symbolic constants as
  25.             _f_a_i_l. The initial value is GGGGLLLL____KKKKEEEEEEEEPPPP.
  26.  
  27.      _z_p_a_s_s  Specifies the stencil action when both the stencil test and the
  28.             depth test pass, or when the stencil test passes and either there
  29.             is no depth buffer or depth testing is not enabled.  _z_p_a_s_s accepts
  30.             the same symbolic constants as _f_a_i_l. The initial value is GGGGLLLL____KKKKEEEEEEEEPPPP.
  31.  
  32. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  33.      Stenciling, like depth-buffering, enables and disables drawing on a per-
  34.      pixel basis.  You draw into the stencil planes using GL drawing
  35.      primitives, then render geometry and images, using the stencil planes to
  36.      mask out portions of the screen.  Stenciling is typically used in
  37.      multipass rendering algorithms to achieve special effects, such as
  38.      decals, outlining, and constructive solid geometry rendering.
  39.  
  40.      The stencil test conditionally eliminates a pixel based on the outcome of
  41.      a comparison between the value in the stencil buffer and a reference
  42.      value. To enable and disable the test, call ggggllllEEEEnnnnaaaabbbblllleeee and ggggllllDDDDiiiissssaaaabbbblllleeee with
  43.      argument GGGGLLLL____SSSSTTTTEEEENNNNCCCCIIIILLLL____TTTTEEEESSSSTTTT; to control it, call ggggllllSSSStttteeeennnncccciiiillllFFFFuuuunnnncccc.
  44.  
  45.      ggggllllSSSStttteeeennnncccciiiillllOOOOpppp takes three arguments that indicate what happens to the
  46.      stored stencil value while stenciling is enabled.  If the stencil test
  47.      fails, no change is made to the pixel's color or depth buffers, and _f_a_i_l
  48.      specifies what happens to the stencil buffer contents.  The following six
  49.      actions are possible.
  50.  
  51.      GGGGLLLL____KKKKEEEEEEEEPPPP         Keeps the current value.
  52.  
  53.      GGGGLLLL____ZZZZEEEERRRROOOO         Sets the stencil buffer value to 0.
  54.  
  55.      GGGGLLLL____RRRREEEEPPPPLLLLAAAACCCCEEEE      Sets the stencil buffer value to _r_e_f, as specified by
  56.                      ggggllllSSSStttteeeennnncccciiiillllFFFFuuuunnnncccc.
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ggggllllSSSStttteeeennnncccciiiillllOOOOpppp((((3333GGGG))))                OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee                ggggllllSSSStttteeeennnncccciiiillllOOOOpppp((((3333GGGG))))
  71.  
  72.  
  73.  
  74.      GGGGLLLL____IIIINNNNCCCCRRRR         Increments the current stencil buffer value.  Clamps to
  75.                      the maximum representable unsigned value.
  76.  
  77.      GGGGLLLL____DDDDEEEECCCCRRRR         Decrements the current stencil buffer value.  Clamps to
  78.                      0.
  79.  
  80.      GGGGLLLL____IIIINNNNVVVVEEEERRRRTTTT       Bitwise inverts the current stencil buffer value.
  81.  
  82.      Stencil buffer values are treated as unsigned integers.  When incremented
  83.                                                    n
  84.      and decremented, values are clamped to 0 and 2 -1, where n is the value
  85.      returned by querying GGGGLLLL____SSSSTTTTEEEENNNNCCCCIIIILLLL____BBBBIIIITTTTSSSS.
  86.  
  87.      The other two arguments to ggggllllSSSStttteeeennnncccciiiillllOOOOpppp specify stencil buffer actions
  88.      that depend on whether subsequent depth buffer tests succeed (_z_p_a_s_s) or
  89.      fail (_z_f_a_i_l) (see
  90.      ggggllllDDDDeeeepppptttthhhhFFFFuuuunnnncccc).  The actions are specified using the same six symbolic
  91.      constants as _f_a_i_l.  Note that _z_f_a_i_l is ignored when there is no depth
  92.      buffer, or when the depth buffer is not enabled.  In these cases, _f_a_i_l
  93.      and _z_p_a_s_s specify stencil action when the stencil test fails and passes,
  94.      respectively.
  95.  
  96. NNNNOOOOTTTTEEEESSSS
  97.      Initially the stencil test is disabled.  If there is no stencil buffer,
  98.      no stencil modification can occur and it is as if the stencil tests
  99.      always pass, regardless of any call to ggggllllSSSStttteeeennnncccciiiillllOOOOpppp.
  100.  
  101. EEEERRRRRRRROOOORRRRSSSS
  102.      GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____EEEENNNNUUUUMMMM is generated if _f_a_i_l, _z_f_a_i_l, or _z_p_a_s_s is any value other
  103.      than the six defined constant values.
  104.  
  105.      GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is generated if ggggllllSSSStttteeeennnncccciiiillllOOOOpppp is executed between the
  106.      execution of ggggllllBBBBeeeeggggiiiinnnn and the corresponding execution of ggggllllEEEEnnnndddd.
  107.  
  108. AAAASSSSSSSSOOOOCCCCIIIIAAAATTTTEEEEDDDD GGGGEEEETTTTSSSS
  109.      ggggllllGGGGeeeetttt with argument GGGGLLLL____SSSSTTTTEEEENNNNCCCCIIIILLLL____FFFFAAAAIIIILLLL
  110.      ggggllllGGGGeeeetttt with argument GGGGLLLL____SSSSTTTTEEEENNNNCCCCIIIILLLL____PPPPAAAASSSSSSSS____DDDDEEEEPPPPTTTTHHHH____PPPPAAAASSSSSSSS
  111.      ggggllllGGGGeeeetttt with argument GGGGLLLL____SSSSTTTTEEEENNNNCCCCIIIILLLL____PPPPAAAASSSSSSSS____DDDDEEEEPPPPTTTTHHHH____FFFFAAAAIIIILLLL
  112.      ggggllllGGGGeeeetttt with argument GGGGLLLL____SSSSTTTTEEEENNNNCCCCIIIILLLL____BBBBIIIITTTTSSSS
  113.      ggggllllIIIIssssEEEEnnnnaaaabbbblllleeeedddd with argument GGGGLLLL____SSSSTTTTEEEENNNNCCCCIIIILLLL____TTTTEEEESSSSTTTT
  114.  
  115.  
  116. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  117.      ggggllllAAAAllllpppphhhhaaaaFFFFuuuunnnncccc, ggggllllBBBBlllleeeennnnddddFFFFuuuunnnncccc, ggggllllDDDDeeeepppptttthhhhFFFFuuuunnnncccc, ggggllllEEEEnnnnaaaabbbblllleeee, ggggllllLLLLooooggggiiiiccccOOOOpppp, ggggllllSSSStttteeeennnncccciiiillllFFFFuuuunnnncccc
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.                                                                         PPPPaaaaggggeeee 2222
  131.  
  132.  
  133.  
  134.